---
title: Utiliser des variables d'environnement
sidebar:
  label: Variables d'environnement
description: Apprendre comment utiliser les variables d'environnement dans un projet Astro.
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro';

Astro vous donne accès à [la prise en charge des variables d'environnement intégrées de Vite](#prise-en-charge-intégrée-de-vite) et inclut certaines [variables d'environnement par défaut pour votre projet](#variables-denvironnement-par-défaut) qui vous permettent d'accéder aux valeurs de configuration de votre projet actuel (par exemple `site`, `base`), que votre projet soit exécuté en mode développement ou production, et plus encore.

Astro fournit également un moyen [d'utiliser et d'organiser vos variables d'environnement avec la sûreté du typage](#variables-denvironnement-avec-sûreté-du-typage). Celui-ci est disponible pour une utilisation dans le contexte Astro (par exemple, les composants Astro, les routes et les points de terminaison, les composants de framework UI, le middleware) et il est géré avec [un schéma dans votre configuration Astro](/fr/reference/configuration-reference/#env).

## Prise en charge intégrée de Vite

Astro utilise la prise en charge intégrée de Vite pour les variables d'environnement, qui sont remplacées statiquement au moment de la compilation, et vous permet [d'utiliser toutes ses méthodes](https://vite.dev/guide/env-and-mode.html) pour travailler avec elles.

Notez que si _toutes_ les variables d'environnement sont disponibles dans le code côté serveur, seules les variables d'environnement préfixées par `PUBLIC_` sont disponibles dans le code côté client pour des raisons de sécurité.

```ini title=".env"
SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there
```

Dans cet exemple, `PUBLIC_ANYBODY` (accessible via `import.meta.env.PUBLIC_ANYBODY`) sera disponible dans le code du serveur ou du client, tandis que `SECRET_PASSWORD` (accessible via `import.meta.env.SECRET_PASSWORD`) ne sera disponible que côté serveur.

:::caution
Les fichiers `.env` ne sont pas chargés dans les [fichiers de configuration](#dans-le-fichier-de-configuration-dastro). 
:::

## Autocomplétion pour TypeScript

Par défaut, Astro fournit une définition de type pour `import.meta.env` dans `astro/client.d.ts`.

Bien que vous puissiez définir davantage de variables d'environnement personnalisées dans les fichiers `.env.[mode]`, vous souhaiterez peut-être obtenir l'IntelliSense TypeScript pour les variables d'environnement définies par l'utilisateur qui sont préfixées par `PUBLIC_`.

Pour y parvenir, vous pouvez créer un fichier `env.d.ts` dans `src/` pour [étendre les types globaux](/fr/guides/typescript/#extension-des-types-globaux) et configurer `ImportMetaEnv` comme ceci :

```ts title="src/env.d.ts"
interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // plus de variables d'environnement...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

## Variables d'environnement par défaut

Astro inclut quelques variables d'environnement par défaut :

- `import.meta.env.MODE` : Le mode dans lequel tourne votre site. C'est `development` lorsque vous exécutez `astro dev` et `production` lorsque vous exécutez `astro build`.
- `import.meta.env.PROD` : `true` si votre site est exécuté en mode production ; `false` sinon.
- `import.meta.env.DEV` : `true` si votre site tourne en développement ; `false` sinon. Toujours l'opposé de `import.meta.env.PROD`.
- `import.meta.env.BASE_URL` : L'URL de base à partir de laquelle votre site est servi. Elle est déterminée par l'option de configuration [`base`](/fr/reference/configuration-reference/#base).
- `import.meta.env.SITE` : C'est [l'option `site`](/fr/reference/configuration-reference/#site) spécifiée dans le fichier `astro.config` de votre projet.
- `import.meta.env.ASSETS_PREFIX` : Le préfixe pour les liens des ressources générées par Astro si l'option de configuration [`build.assetsPrefix`](/fr/reference/configuration-reference/#buildassetsprefix) est définie. Ceci peut être utilisé pour créer des liens de ressources non gérés par Astro.

Utilisez-les comme n'importe quelle autre variable d'environnement.

```ts utils.ts
const isProd = import.meta.env.PROD;
const isDev = import.meta.env.DEV;
```

## Définir des variables d'environnement

### Le fichier `.env`

Les variables d'environnement peuvent être chargées à partir des fichiers `.env` dans le répertoire de votre projet.

Créez simplement un fichier `.env` dans le répertoire du projet et ajoutez-y quelques variables.

```ini title=".env"
# Elle sera disponible uniquement pour le code exécuté sur le serveur !
DB_PASSWORD="foobar"

# Elle sera disponible partout !
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"
```

Vous pouvez également ajouter `.production`, `.development` ou un nom de mode personnalisé au nom de fichier lui-même (par exemple `.env.testing`, `.env.staging`). Cela vous permet d'utiliser différents ensembles de variables d'environnement à différents moments.

Les commandes `astro dev` et `astro build` sont par défaut respectivement en modes `"development"` et `"production"`. Vous pouvez exécuter ces commandes avec l'option [`--mode`](/fr/reference/cli-reference/#--mode-string) pour transmettre une valeur différente pour `mode` et charger le fichier `.env` correspondant.

Cela vous permet d'exécuter le serveur de développement ou de créer votre site en vous connectant à différentes API :

<PackageManagerTabs>
 <Fragment slot="npm">
    ```shell
    #  Exécute le serveur de développement connecté à une API « staging »
    npm run astro dev -- --mode staging

    # Crée un site qui se connecte à une API de « production » avec des informations de débogage supplémentaires
    npm run astro build -- --devOutput

    # Crée un site qui se connecte à une API de « test »
    npm run astro build -- --mode testing
    ```
 </Fragment>
 <Fragment slot="pnpm">
    ```shell
    #  Exécute le serveur de développement connecté à une API « staging »
    pnpm astro dev --mode staging

    # Crée un site qui se connecte à une API de « production » avec des informations de débogage supplémentaires
    pnpm astro build --devOutput

    # Crée un site qui se connecte à une API de « test »
    pnpm astro build --mode testing
    ```
 </Fragment>
  <Fragment slot="yarn">
    ```shell
    #  Exécute le serveur de développement connecté à une API « staging »
    yarn astro dev --mode staging

    # Crée un site qui se connecte à une API de « production » avec des informations de débogage supplémentaires
    yarn astro build --devOutput

    # Crée un site qui se connecte à une API de « test »
    yarn astro build --mode testing
    ```
 </Fragment>
</PackageManagerTabs>

Pour plus d'informations sur les fichiers `.env`, [voir la documentation de Vite (Anglais)](https://vite.dev/guide/env-and-mode.html#env-files).

### Dans le fichier de configuration d'Astro

Astro évalue les fichiers de configuration avant de charger vos autres fichiers. Cela signifie que vous ne pouvez pas utiliser `import.meta.env` dans `astro.config.mjs` pour accéder aux variables d'environnement qui ont été définies dans les fichiers `.env`.

Vous pouvez utiliser `process.env` dans un fichier de configuration pour accéder à d'autres variables d'environnement, comme celles [définies par la CLI](#en-utilisant-la-cli).

Vous pouvez également utiliser [l'assistant `loadEnv` de Vite](https://main.vite.dev/config/#using-environment-variables-in-config) pour charger manuellement les fichiers `.env`.

```js title="astro.config.mjs"
import { loadEnv } from "vite";

const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");
```

:::note
`pnpm` ne vous permet pas d'importer des modules qui ne sont pas directement installés dans votre projet. Si vous utilisez `pnpm`, vous devrez installer `vite` pour utiliser l'assistant `loadEnv`.

```sh
pnpm add -D vite
```
:::

### En utilisant la CLI

Vous pouvez également ajouter des variables d'environnement lorsque vous exécutez votre projet :

<PackageManagerTabs>
 <Fragment slot="yarn">
    ```shell
    PUBLIC_POKEAPI=https://pokeapi.co/api/v2 yarn run dev
    ```
 </Fragment>
 <Fragment slot="npm">
    ```shell
    PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev
    ```
 </Fragment>
 <Fragment slot="pnpm">
    ```shell
    PUBLIC_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev
    ```
 </Fragment>
</PackageManagerTabs>

## Obtenir des variables d'environnement

Les variables d'environnement dans Astro sont accessibles avec `import.meta.env`, en utilisant la fonctionnalité [`import.meta` ajoutée dans ES2020](https://tc39.es/ecma262/2020/#prod-ImportMeta), au lieu de `process.env`.

Par exemple, utilisez `import.meta.env.PUBLIC_POKEAPI` pour obtenir la variable d'environnement `PUBLIC_POKEAPI`.

```js /(?<!//.*)import.meta.env.[A-Z_]+/
// Quand import.meta.env.SSR === true
const data = await db(import.meta.env.DB_PASSWORD);

// Quand import.meta.env.SSR === false
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);
```

Lorsque vous utilisez SSR, les variables d'environnement peuvent être accédées au moment de l'exécution en fonction de l'adaptateur SSR utilisé. Avec la plupart des adaptateurs, vous pouvez accéder aux variables d'environnement avec `process.env`, mais certains adaptateurs fonctionnent différemment. Pour l'adaptateur Deno, vous utiliserez `Deno.env.get()`. Voir comment [accéder à l'environnement d'exécution de Cloudflare](/fr/guides/integrations-guide/cloudflare/#environnement-dexécution-cloudflare) pour gérer les variables d'environnement lors de l'utilisation de l'adaptateur Cloudflare. Astro vérifiera d'abord l'environnement du serveur pour les variables, et si elles n'existent pas, Astro les cherchera dans les fichiers `.env`.

## Variables d'environnement avec sûreté du typage

L'API `astro:env` vous permet de configurer un schéma avec sûreté du typage pour [les variables d'environnement que vous avez définies](#définir-des-variables-denvironnement). Cela vous permet d'indiquer s'ils doivent être disponibles sur le serveur ou le client, et de définir leur type de données et leurs propriétés supplémentaires.

<ReadMore>Vous développez un adaptateur ? Découvrez comment [rendre un adaptateur compatible avec `astro:env`](/fr/reference/adapter-reference/#envgetsecret).</ReadMore>

### Utilisation de base

#### Définissez votre schéma

Pour configurer un schéma, ajoutez l'option `env.schema` à votre configuration Astro :

```js title="astro.config.mjs" ins={4-8}
import { defineConfig } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      // ...
    }
  }
})
```

Vous pouvez ensuite [enregistrer des variables sous forme de chaîne de caractères, de nombre, d'énumération ou de booléen](#types-de-données) en utilisant l'assistant `envField`. Définissez le [type de variable d'environnement](#types-de-variables) en fournissant les propriétés `context` (`"client"` ou `"server"`) et `access` (`"secret"` ou `"public"`) pour chaque variable, et transmettez toutes les propriétés supplémentaires telles que `optional` ou `default` dans un objet :

```js title="astro.config.mjs" ins="envField"
import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({ context: "client", access: "public", optional: true }),
      PORT: envField.number({ context: "server", access: "public", default: 4321 }),
      API_SECRET: envField.string({ context: "server", access: "secret" }),
    }
  }
})
```

Les types seront générés pour vous lors de l'exécution de `astro dev` ou `astro build`, mais vous pouvez exécuter `astro sync` pour générer des types uniquement.

#### Utiliser les variables de votre schéma

Importez et utilisez vos variables définies à partir du module `/client` ou `/server` approprié :

```astro
---
import { API_URL } from "astro:env/client";
import { API_SECRET_TOKEN } from "astro:env/server";

const data = await fetch(`${API_URL}/users`, {
	method: "GET",
	headers: {
		"Content-Type": "application/json",
		"Authorization": `Bearer ${API_SECRET_TOKEN}`
	},
})
---

<script>
  import { API_URL } from "astro:env/client";

  fetch(`${API_URL}/ping`);
</script>
```

### Types de variables

Il existe trois types de variables d'environnement, déterminées par la combinaison des paramètres `context` (`"client"` ou `"server"`) et `access` (`"secret"` ou `"public"`) définis dans votre schéma :

- **Variables publiques du client** : Ces variables se retrouvent à la fois dans vos regroupements client et serveur finaux et sont accessibles à la fois depuis le client et le serveur via le module `astro:env/client` :

   ```js
   import { API_URL } from "astro:env/client";
   ```

- **Variables publiques du serveur** : Ces variables se retrouvent dans votre regroupement de serveur final et sont accessibles sur le serveur via le module `astro:env/server` :

   ```js
   import { PORT } from "astro:env/server";
   ```

- **Variables secrètes du serveur** : Ces variables ne font pas partie de votre regroupement final et sont accessibles sur le serveur via le module `astro:env/server` :

   ```js
   import { API_SECRET } from "astro:env/server";
   ```

   Par défaut, tous les secrets sont validés chaque fois qu'un élément est importé du module `astro:env/server`. Cela signifie que les secrets peuvent être validés même s'ils ne sont pas importés. Vous devrez peut-être [transmettre des variables d'environnement factices](#définir-des-variables-denvironnement) pour satisfaire cette validation lors de la compilation.

   Vous pouvez également activer la validation des secrets au démarrage en [configurant `validateSecrets: true`](/fr/reference/configuration-reference/#envvalidatesecrets).

:::note
Les **variables secrètes du client** ne sont pas prises en charge car il n'existe aucun moyen sûr d'envoyer ces données au client. Par conséquent, il n'est pas possible de configurer à la fois `context: "client"` et `access: "secret"` dans votre schéma.
:::

### Types de données

Il existe actuellement quatre types de données pris en charge : les chaînes de caractères, les nombres, les énumérations et les booléens :

```js
import { envField } from "astro/config";

envField.string({
   // context & access
   optional: true,
   default: "foo",
})

envField.number({
   // context & access
   optional: true,
   default: 15,
})

envField.boolean({
   // context & access
   optional: true,
   default: true,
})

envField.enum({
   // context & access
   values: ["foo", "bar", "baz"],
   optional: true,
   default: "baz",
})
```

<ReadMore>Pour une liste complète des champs de validation, consultez la [référence de l'API `envField`](/fr/reference/configuration-reference/#envschema).</ReadMore>

### Récupérer des secrets de manière dynamique

Malgré la définition de votre schéma, vous souhaiterez peut-être récupérer la valeur brute d'un secret donné ou récupérer des secrets non définis dans votre schéma. Dans ce cas, vous pouvez utiliser `getSecret()` exporté depuis `astro:env/server` :

```js
import {
   FOO, // boolean
   getSecret
} from "astro:env/server";

getSecret("FOO"); // string | undefined
```

<ReadMore>Apprenez-en davantage dans [la référence de l'API](/fr/reference/modules/astro-env/#getsecret).</ReadMore>

### Limitations

`astro:env` est un module virtuel, ce qui signifie qu'il ne peut être utilisé que dans le contexte Astro. Par exemple, vous pouvez l'utiliser dans :

- les Middlewares
- les routes et points de terminaison Astro
- les composants Astro
- les composants de framework
- les modules

Vous ne pouvez pas l'utiliser dans ce qui suit et devrez recourir à `process.env` :

- `astro.config.mjs`
- les scripts
